Plugins/Gaim Service/Libgaim.framework/Versions/A/Headers/notify.h

   1 /**
   2  * @file notify.h Notification API
   3  * @ingroup core
   4  *
   5  * gaim
   6  *
   7  * Gaim is the legal property of its developers, whose names are too numerous
   8  * to list here.  Please refer to the COPYRIGHT file distributed with this
   9  * source distribution.
  10  *
  11  * This program is free software; you can redistribute it and/or modify
  12  * it under the terms of the GNU General Public License as published by
  13  * the Free Software Foundation; either version 2 of the License, or
  14  * (at your option) any later version.
  15  *
  16  * This program is distributed in the hope that it will be useful,
  17  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  19  * GNU General Public License for more details.
  20  *
  21  * You should have received a copy of the GNU General Public License
  22  * along with this program; if not, write to the Free Software
  23  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  24  */
  25 #ifndef _GAIM_NOTIFY_H_
  26 #define _GAIM_NOTIFY_H_
  27
  28 #include <stdlib.h>
  29 #include <glib-object.h>
  30 #include <glib.h>
  31
  32 typedef struct _GaimNotifyUserInfoEntry GaimNotifyUserInfoEntry;
  33 typedef struct _GaimNotifyUserInfo      GaimNotifyUserInfo;
  34
  35 #include "connection.h"
  36
  37 /**
  38  * Notification close callbacks.
  39  */
  40 typedef void  (*GaimNotifyCloseCallback) (gpointer user_data);
  41
  42
  43 /**
  44  * Notification types.
  45  */
  46 typedef enum
  47 {
  48         GAIM_NOTIFY_MESSAGE = 0,   /**< Message notification.         */
  49         GAIM_NOTIFY_EMAIL,         /**< Single e-mail notification.   */
  50         GAIM_NOTIFY_EMAILS,        /**< Multiple e-mail notification. */
  51         GAIM_NOTIFY_FORMATTED,     /**< Formatted text.               */
  52         GAIM_NOTIFY_SEARCHRESULTS, /**< Buddy search results.         */
  53         GAIM_NOTIFY_USERINFO,      /**< Formatted userinfo text.      */
  54         GAIM_NOTIFY_URI            /**< URI notification or display.  */
  55
  56 } GaimNotifyType;
  57
  58
  59 /**
  60  * Notification message types.
  61  */
  62 typedef enum
  63 {
  64         GAIM_NOTIFY_MSG_ERROR   = 0, /**< Error notification.       */
  65         GAIM_NOTIFY_MSG_WARNING,     /**< Warning notification.     */
  66         GAIM_NOTIFY_MSG_INFO         /**< Information notification. */
  67
  68 } GaimNotifyMsgType;
  69
  70
  71 /**
  72  * The types of buttons
  73  */
  74 typedef enum
  75 {
  76         GAIM_NOTIFY_BUTTON_LABELED = 0,  /**< special use, see _button_add_labeled */
  77         GAIM_NOTIFY_BUTTON_CONTINUE = 1,
  78         GAIM_NOTIFY_BUTTON_ADD,
  79         GAIM_NOTIFY_BUTTON_INFO,
  80         GAIM_NOTIFY_BUTTON_IM,
  81         GAIM_NOTIFY_BUTTON_JOIN,
  82         GAIM_NOTIFY_BUTTON_INVITE
  83 } GaimNotifySearchButtonType;
  84
  85
  86 /**
  87  * Search results object.
  88  */
  89 typedef struct
  90 {
  91         GList *columns;        /**< List of the search column objects. */
  92         GList *rows;           /**< List of rows in the result. */
  93         GList *buttons;        /**< List of buttons to display. */
  94
  95 } GaimNotifySearchResults;
  96
  97 /**
  98  * Types of GaimNotifyUserInfoEntry objects
  99  */
 100 typedef enum
 101 {
 102         GAIM_NOTIFY_USER_INFO_ENTRY_PAIR = 0,
 103         GAIM_NOTIFY_USER_INFO_ENTRY_SECTION_BREAK,
 104         GAIM_NOTIFY_USER_INFO_ENTRY_SECTION_HEADER
 105 } GaimNotifyUserInfoEntryType;
 106
 107 /**
 108  * Single column of a search result.
 109  */
 110 typedef struct
 111 {
 112         char *title; /**< Title of the column. */
 113
 114 } GaimNotifySearchColumn;
 115
 116
 117 /**
 118  * Callback for a button in a search result.
 119  *
 120  * @param c         the GaimConnection passed to gaim_notify_searchresults
 121  * @param row       the contents of the selected row
 122  * @param user_data User defined data.
 123  */
 124 typedef void (*GaimNotifySearchResultsCallback)(GaimConnection *c, GList *row,
 125                                                                                                 gpointer user_data);
 126
 127
 128 /**
 129  * Definition of a button.
 130  */
 131 typedef struct
 132 {
 133         GaimNotifySearchButtonType type;
 134         GaimNotifySearchResultsCallback callback; /**< Function to be called when clicked. */
 135         char *label;                              /**< only for GAIM_NOTIFY_BUTTON_LABELED */
 136 } GaimNotifySearchButton;
 137
 138
 139 /**
 140  * Notification UI operations.
 141  */
 142 typedef struct
 143 {
 144         void *(*notify_message)(GaimNotifyMsgType type, const char *title,
 145                                 const char *primary, const char *secondary);
 146
 147         void *(*notify_email)(GaimConnection *gc,
 148                               const char *subject, const char *from,
 149                               const char *to, const char *url);
 150
 151         void *(*notify_emails)(GaimConnection *gc,
 152                                size_t count, gboolean detailed,
 153                                const char **subjects, const char **froms,
 154                                const char **tos, const char **urls);
 155
 156         void *(*notify_formatted)(const char *title, const char *primary,
 157                                   const char *secondary, const char *text);
 158
 159         void *(*notify_searchresults)(GaimConnection *gc, const char *title,
 160                                       const char *primary, const char *secondary,
 161                                       GaimNotifySearchResults *results, gpointer user_data);
 162
 163         void (*notify_searchresults_new_rows)(GaimConnection *gc,
 164                                               GaimNotifySearchResults *results,
 165                                               void *data);
 166
 167         void *(*notify_userinfo)(GaimConnection *gc, const char *who,
 168                                  GaimNotifyUserInfo *user_info);
 169
 170         void *(*notify_uri)(const char *uri);
 171
 172         void (*close_notify)(GaimNotifyType type, void *ui_handle);
 173
 174 } GaimNotifyUiOps;
 175
 176
 177 #ifdef __cplusplus
 178 extern "C" {
 179 #endif
 180
 181
 182 /**************************************************************************/
 183 /** Search results notification API                                       */
 184 /**************************************************************************/
 185 /*@{*/
 186
 187 /**
 188  * Displays results from a buddy search.  This can be, for example,
 189  * a window with a list of all found buddies, where you are given the
 190  * option of adding buddies to your buddy list.
 191  *
 192  * @param gc        The GaimConnection handle associated with the information.
 193  * @param title     The title of the message.  If this is NULL, the title
 194  *                  will be "Search Results."
 195  * @param primary   The main point of the message.
 196  * @param secondary The secondary information.
 197  * @param results   The GaimNotifySearchResults instance.
 198  * @param cb        The callback to call when the user closes
 199  *                  the notification.
 200  * @param user_data The data to pass to the close callback and any other
 201  *                  callback associated with a button.
 202  *
 203  * @return A UI-specific handle.
 204  */
 205 void *gaim_notify_searchresults(GaimConnection *gc, const char *title,
 206                                                                 const char *primary, const char *secondary,
 207                                                                 GaimNotifySearchResults *results, GaimNotifyCloseCallback cb,
 208                                                                 gpointer user_data);
 209
 210 void gaim_notify_searchresults_free(GaimNotifySearchResults *results);
 211
 212 /**
 213  * Replace old rows with the new. Reuse an existing window.
 214  *
 215  * @param gc        The GaimConnection structure.
 216  * @param results   The GaimNotifySearchResults structure.
 217  * @param data      Data returned by the gaim_notify_searchresults().
 218  */
 219 void gaim_notify_searchresults_new_rows(GaimConnection *gc,
 220                                                                                 GaimNotifySearchResults *results,
 221                                                                                 void *data);
 222
 223
 224 /**
 225  * Adds a stock button that will be displayed in the search results dialog.
 226  *
 227  * @param results The search results object.
 228  * @param type    Type of the button. (TODO: Only one button of a given type can be displayed.)
 229  * @param cb      Function that will be called on the click event.
 230  */
 231 void gaim_notify_searchresults_button_add(GaimNotifySearchResults *results,
 232                                                                                   GaimNotifySearchButtonType type,
 233                                                                                   GaimNotifySearchResultsCallback cb);
 234
 235
 236 /**
 237  * Adds a plain labelled button that will be displayed in the search results dialog.
 238  *
 239  * @param results The search results object
 240  * @param label   The label to display
 241  * @param cb      Function that will be called on the click event
 242  */
 243 void gaim_notify_searchresults_button_add_labeled(GaimNotifySearchResults *results,
 244                                                   const char *label,
 245                                                   GaimNotifySearchResultsCallback cb);
 246
 247
 248 /**
 249  * Returns a newly created search results object.
 250  *
 251  * @return The new search results object.
 252  */
 253 GaimNotifySearchResults *gaim_notify_searchresults_new(void);
 254
 255 /**
 256  * Returns a newly created search result column object.
 257  *
 258  * @param title Title of the column. NOTE: Title will get g_strdup()ed.
 259  *
 260  * @return The new search column object.
 261  */
 262 GaimNotifySearchColumn *gaim_notify_searchresults_column_new(const char *title);
 263
 264 /**
 265  * Adds a new column to the search result object.
 266  *
 267  * @param results The result object to which the column will be added.
 268  * @param column The column that will be added to the result object.
 269  */
 270 void gaim_notify_searchresults_column_add(GaimNotifySearchResults *results,
 271                                                                                   GaimNotifySearchColumn *column);
 272
 273 /**
 274  * Adds a new row of the results to the search results object.
 275  *
 276  * @param results The search results object.
 277  * @param row     The row of the results.
 278  */
 279 void gaim_notify_searchresults_row_add(GaimNotifySearchResults *results,
 280                                                                            GList *row);
 281
 282 /**
 283  * Returns a number of the rows in the search results object.
 284  *
 285  * @param results The search results object.
 286  *
 287  * @return Number of the result rows.
 288  */
 289 guint gaim_notify_searchresults_get_rows_count(GaimNotifySearchResults *results);
 290
 291 /**
 292  * Returns a number of the columns in the search results object.
 293  *
 294  * @param results The search results object.
 295  *
 296  * @return Number of the columns.
 297  */
 298 guint gaim_notify_searchresults_get_columns_count(GaimNotifySearchResults *results);
 299
 300 /**
 301  * Returns a row of the results from the search results object.
 302  *
 303  * @param results The search results object.
 304  * @param row_id  Index of the row to be returned.
 305  *
 306  * @return Row of the results.
 307  */
 308 GList *gaim_notify_searchresults_row_get(GaimNotifySearchResults *results,
 309                                                                                  unsigned int row_id);
 310
 311 /**
 312  * Returns a title of the search results object's column.
 313  *
 314  * @param results   The search results object.
 315  * @param column_id Index of the column.
 316  *
 317  * @return Title of the column.
 318  */
 319 char *gaim_notify_searchresults_column_get_title(GaimNotifySearchResults *results,
 320                                                                                                  unsigned int column_id);
 321
 322 /*@}*/
 323
 324 /**************************************************************************/
 325 /** @name Notification API                                                */
 326 /**************************************************************************/
 327 /*@{*/
 328
 329 /**
 330  * Displays a notification message to the user.
 331  *
 332  * @param handle    The plugin or connection handle.
 333  * @param type      The notification type.
 334  * @param title     The title of the message.
 335  * @param primary   The main point of the message.
 336  * @param secondary The secondary information.
 337  * @param cb        The callback to call when the user closes
 338  *                  the notification.
 339  * @param user_data The data to pass to the callback.
 340  *
 341  * @return A UI-specific handle.
 342  */
 343 void *gaim_notify_message(void *handle, GaimNotifyMsgType type,
 344                                                   const char *title, const char *primary,
 345                                                   const char *secondary, GaimNotifyCloseCallback cb,
 346                                                   gpointer user_data);
 347
 348 /**
 349  * Displays a single e-mail notification to the user.
 350  *
 351  * @param handle    The plugin or connection handle.
 352  * @param subject   The subject of the e-mail.
 353  * @param from      The from address.
 354  * @param to        The destination address.
 355  * @param url       The URL where the message can be read.
 356  * @param cb        The callback to call when the user closes
 357  *                  the notification.
 358  * @param user_data The data to pass to the callback.
 359  *
 360  * @return A UI-specific handle.
 361  */
 362 void *gaim_notify_email(void *handle, const char *subject,
 363                                                 const char *from, const char *to,
 364                                                 const char *url, GaimNotifyCloseCallback cb,
 365                                                 gpointer user_data);
 366
 367 /**
 368  * Displays a notification for multiple e-mails to the user.
 369  *
 370  * @param handle    The plugin or connection handle.
 371  * @param count     The number of e-mails.
 372  * @param detailed  @c TRUE if there is information for each e-mail in the
 373  *                  arrays.
 374  * @param subjects  The array of subjects.
 375  * @param froms     The array of from addresses.
 376  * @param tos       The array of destination addresses.
 377  * @param urls      The URLs where the messages can be read.
 378  * @param cb        The callback to call when the user closes
 379  *                  the notification.
 380  * @param user_data The data to pass to the callback.
 381  *
 382  * @return A UI-specific handle.
 383  */
 384 void *gaim_notify_emails(void *handle, size_t count, gboolean detailed,
 385                                                  const char **subjects, const char **froms,
 386                                                  const char **tos, const char **urls,
 387                                                  GaimNotifyCloseCallback cb, gpointer user_data);
 388
 389 /**
 390  * Displays a notification with formatted text.
 391  *
 392  * The text is essentially a stripped-down format of HTML, the same that
 393  * IMs may send.
 394  *
 395  * @param handle    The plugin or connection handle.
 396  * @param title     The title of the message.
 397  * @param primary   The main point of the message.
 398  * @param secondary The secondary information.
 399  * @param text      The formatted text.
 400  * @param cb        The callback to call when the user closes
 401  *                  the notification.
 402  * @param user_data The data to pass to the callback.
 403  *
 404  * @return A UI-specific handle.
 405  */
 406 void *gaim_notify_formatted(void *handle, const char *title,
 407                                                         const char *primary, const char *secondary,
 408                                                         const char *text, GaimNotifyCloseCallback cb, gpointer user_data);
 409
 410 /**
 411  * Displays user information with formatted text, passing information giving
 412  * the connection and username from which the user information came.
 413  *
 414  * The text is essentially a stripped-down format of HTML, the same that
 415  * IMs may send.
 416  *
 417  * @param gc                     The GaimConnection handle associated with the information.
 418  * @param who                            The username associated with the information.
 419  * @param user_info          The GaimNotifyUserInfo which contains the information
 420  * @param cb                 The callback to call when the user closes
 421  *                           the notification.
 422  * @param user_data          The data to pass to the callback.
 423  *
 424  * @return A UI-specific handle.
 425  */
 426 void *gaim_notify_userinfo(GaimConnection *gc, const char *who,
 427                                                    GaimNotifyUserInfo *user_info, GaimNotifyCloseCallback cb,
 428                                                    gpointer user_data);
 429
 430 /**
 431  * Create a new GaimNotifyUserInfo which is suitable for passing to gaim_notify_userinfo()
 432  *
 433  * @return A new GaimNotifyUserInfo, which the caller must destroy when done
 434  */
 435 GaimNotifyUserInfo *gaim_notify_user_info_new(void);
 436
 437 /**
 438  * Destroy a GaimNotifyUserInfo
 439  *
 440  * @param user_info          The GaimNotifyUserInfo
 441  */
 442 void gaim_notify_user_info_destroy(GaimNotifyUserInfo *user_info);
 443
 444 /**
 445  * Retrieve the array of GaimNotifyUserInfoEntry objects from a GaimNotifyUserInfo
 446  *
 447  * This GList may be manipulated directly with normal GList functions such as g_list_insert(). Only
 448  * GaimNotifyUserInfoEntry are allowed in the list.  If a GaimNotifyUserInfoEntry item is added to the list,
 449  * it should not be g_free()'d by the caller; GaimNotifyUserInfo will g_free it when destroyed.
 450  *
 451  * To remove a GaimNotifyUserInfoEntry, use gaim_notify_user_info_remove_entry(). Do not use the GList directly.
 452  *
 453  * @param user_info          The GaimNotifyUserInfo
 454  *
 455  * @result                   A GList of GaimNotifyUserInfoEntry objects
 456  */
 457 GList *gaim_notify_user_info_get_entries(GaimNotifyUserInfo *user_info);
 458
 459 /**
 460  * Create a textual representation of a GaimNotifyUserInfo, separating entries with newline
 461  *
 462  * @param user_info          The GaimNotifyUserInfo
 463  * @param newline            The separation character
 464  */
 465 char *gaim_notify_user_info_get_text_with_newline(GaimNotifyUserInfo *user_info, const char *newline);
 466
 467 /**
 468  * Add a label/value pair to a GaimNotifyUserInfo object.
 469  * GaimNotifyUserInfo keeps track of the order in which pairs are added.
 470  *
 471  * @param user_info          The GaimNotifyUserInfo
 472  * @param label              A label, which for example might be displayed by a UI with a colon after it ("Status:"). Do not include a colon.
 473  *                           If NULL, value will be displayed without a label.
 474  * @param value              The value, which might be displayed by a UI after the label.
 475  *                           If NULL, label will still be displayed; the UI should then treat label as independent
 476  *                           and not include a colon if it would otherwise.
 477  */
 478 void gaim_notify_user_info_add_pair(GaimNotifyUserInfo *user_info, const char *label, const char *value);
 479
 480 /**
 481  * Prepend a label/value pair to a GaimNotifyUserInfo object
 482  *
 483  * @param user_info          The GaimNotifyUserInfo
 484  * @param label              A label, which for example might be displayed by a UI with a colon after it ("Status:"). Do not include a colon.
 485  *                           If NULL, value will be displayed without a label.
 486  * @param value              The value, which might be displayed by a UI after the label.
 487  *                           If NULL, label will still be displayed; the UI should then treat label as independent
 488  *                           and not include a colon if it would otherwise.
 489  */
 490 void gaim_notify_user_info_prepend_pair(GaimNotifyUserInfo *user_info, const char *label, const char *value);
 491
 492 /**
 493  * Remove a GaimNotifyUserInfoEntry from a GaimNotifyUserInfo object
 494  *
 495  * @param user_info          The GaimNotifyUserInfo
 496  * @param user_info_entry    The GaimNotifyUserInfoEntry
 497  */
 498 void gaim_notify_user_info_remove_entry(GaimNotifyUserInfo *user_info, GaimNotifyUserInfoEntry *user_info_entry);
 499 /**
 500  * Create a new GaimNotifyUserInfoEntry
 501  *
 502  * If added to a GaimNotifyUserInfo object, this should not be free()'d, as GaimNotifyUserInfo will do so
 503  * when destroyed.  gaim_notify_user_info_add_pair() and gaim_notify_user_info_prepend_pair() are convenience
 504  * methods for creating entries and adding them to a GaimNotifyUserInfo.
 505  *
 506  * @param label              A label, which for example might be displayed by a UI with a colon after it ("Status:"). Do not include a colon.
 507  *                           If NULL, value will be displayed without a label.
 508  * @param value              The value, which might be displayed by a UI after the label.
 509  *                           If NULL, label will still be displayed; the UI should then treat label as independent
 510  *                           and not include a colon if it would otherwise.
 511  *
 512  * @result A new GaimNotifyUserInfoEntry
 513  */
 514 GaimNotifyUserInfoEntry *gaim_notify_user_info_entry_new(const char *label, const char *value);
 515
 516 /**
 517  * Add a section break.  A UI might display this as a horizontal line.
 518  *
 519  * @param user_info          The GaimNotifyUserInfo
 520  */
 521 void gaim_notify_user_info_add_section_break(GaimNotifyUserInfo *user_info);
 522
 523 /**
 524  * Add a section header.  A UI might display this in a different font from other text.
 525  *
 526  * @param user_info          The GaimNotifyUserInfo
 527  * @param label              The name of the section
 528  */
 529 void gaim_notify_user_info_add_section_header(GaimNotifyUserInfo *user_info, const char *label);
 530
 531 /**
 532  * Remove the last item which was added to a GaimNotifyUserInfo. This could be used to remove a section header which is not needed.
 533  */
 534 void gaim_notify_user_info_remove_last_item(GaimNotifyUserInfo *user_info);
 535
 536 /**
 537  * Get the label for a GaimNotifyUserInfoEntry
 538  *
 539  * @param user_info_entry     The GaimNotifyUserInfoEntry
 540  *
 541  * @result                    The label
 542  */
 543 gchar *gaim_notify_user_info_entry_get_label(GaimNotifyUserInfoEntry *user_info_entry);
 544
 545 /**
 546  * Set the label for a GaimNotifyUserInfoEntry
 547  *
 548  * @param user_info_entry     The GaimNotifyUserInfoEntry
 549  * @param label                       The label
 550  */
 551 void gaim_notify_user_info_entry_set_label(GaimNotifyUserInfoEntry *user_info_entry, const char *label);
 552
 553 /**
 554  * Get the value for a GaimNotifyUserInfoEntry
 555  *
 556  * @param user_info_entry     The GaimNotifyUserInfoEntry
 557  *
 558  * @result                    The value
 559  */
 560 gchar *gaim_notify_user_info_entry_get_value(GaimNotifyUserInfoEntry *user_info_entry);
 561
 562 /**
 563  * Set the value for a GaimNotifyUserInfoEntry
 564  *
 565  * @param user_info_entry     The GaimNotifyUserInfoEntry
 566  * @param value                           The value
 567  */
 568 void gaim_notify_user_info_entry_set_value(GaimNotifyUserInfoEntry *user_info_entry, const char *value);
 569
 570
 571 /**
 572  * Get the type of a GaimNotifyUserInfoEntry
 573  *
 574  * @param user_info_entry     The GaimNotifyUserInfoEntry
 575  *
 576  * @result                                        The GaimNotifyUserInfoEntryType
 577  */
 578 GaimNotifyUserInfoEntryType gaim_notify_user_info_entry_get_type(GaimNotifyUserInfoEntry *user_info_entry);
 579
 580 /**
 581  * Set the type of a GaimNotifyUserInfoEntry
 582  *
 583  * @param user_info_entry     The GaimNotifyUserInfoEntry
 584  * @param                                         The GaimNotifyUserInfoEntryType
 585  */
 586 void gaim_notify_user_info_entry_set_type(GaimNotifyUserInfoEntry *user_info_entry,
 587                                                                                   GaimNotifyUserInfoEntryType type);
 588
 589 /**
 590  * Opens a URI or somehow presents it to the user.
 591  *
 592  * @param handle The plugin or connection handle.
 593  * @param uri    The URI to display or go to.
 594  *
 595  * @return A UI-specific handle, if any. This may only be presented if
 596  *         the UI code displays a dialog instead of a webpage, or something
 597  *         similar.
 598  */
 599 void *gaim_notify_uri(void *handle, const char *uri);
 600
 601 /**
 602  * Closes a notification.
 603  *
 604  * This should be used only by the UI operation functions and part of the
 605  * core.
 606  *
 607  * @param type      The notification type.
 608  * @param ui_handle The notification UI handle.
 609  */
 610 void gaim_notify_close(GaimNotifyType type, void *ui_handle);
 611
 612 /**
 613  * Closes all notifications registered with the specified handle.
 614  *
 615  * @param handle The handle.
 616  */
 617 void gaim_notify_close_with_handle(void *handle);
 618
 619 /**
 620  * A wrapper for gaim_notify_message that displays an information message.
 621  */
 622 #define gaim_notify_info(handle, title, primary, secondary) \
 623         gaim_notify_message((handle), GAIM_NOTIFY_MSG_INFO, (title), \
 624                                                 (primary), (secondary), NULL, NULL)
 625
 626 /**
 627  * A wrapper for gaim_notify_message that displays a warning message.
 628  */
 629 #define gaim_notify_warning(handle, title, primary, secondary) \
 630         gaim_notify_message((handle), GAIM_NOTIFY_MSG_WARNING, (title), \
 631                                                 (primary), (secondary), NULL, NULL)
 632
 633 /**
 634  * A wrapper for gaim_notify_message that displays an error message.
 635  */
 636 #define gaim_notify_error(handle, title, primary, secondary) \
 637         gaim_notify_message((handle), GAIM_NOTIFY_MSG_ERROR, (title), \
 638                                                 (primary), (secondary), NULL, NULL)
 639
 640 /*@}*/
 641
 642 /**************************************************************************/
 643 /** @name UI Registration Functions                                       */
 644 /**************************************************************************/
 645 /*@{*/
 646
 647 /**
 648  * Sets the UI operations structure to be used when displaying a
 649  * notification.
 650  *
 651  * @param ops The UI operations structure.
 652  */
 653 void gaim_notify_set_ui_ops(GaimNotifyUiOps *ops);
 654
 655 /**
 656  * Returns the UI operations structure to be used when displaying a
 657  * notification.
 658  *
 659  * @return The UI operations structure.
 660  */
 661 GaimNotifyUiOps *gaim_notify_get_ui_ops(void);
 662
 663 /*@}*/
 664
 665 /**************************************************************************/
 666 /** @name Notify Subsystem                                         */
 667 /**************************************************************************/
 668 /*@{*/
 669
 670 /**
 671  * Returns the notify subsystem handle.
 672  *
 673  * @return The notify subsystem handle.
 674  */
 675 void *gaim_notify_get_handle(void);
 676
 677 /**
 678  * Initializes the notify subsystem.
 679  */
 680 void gaim_notify_init(void);
 681
 682 /**
 683  * Uninitializes the notify subsystem.
 684  */
 685 void gaim_notify_uninit(void);
 686
 687 /*@}*/
 688
 689
 690 #ifdef __cplusplus
 691 }
 692 #endif
 693
 694 #endif /* _GAIM_NOTIFY_H_ */